home *** CD-ROM | disk | FTP | other *** search
/ GFX Sensations 1 / Graphic Sensations - Volume 1.iso / tools / amiga / 3d_tools / shelly14.lha / shelly / Shelly.doc < prev    next >
Text File  |  1994-04-24  |  20KB  |  608 lines
  1.                                                              14.4.1994
  2.  
  3. Welcome to:
  4.  
  5.               SHELLY V1.4
  6.  
  7.         INTRODUCTION:
  8.         ¯¯¯¯¯¯¯¯¯¯¯¯¯
  9.         
  10.         Shelly is a little tool that generates 3D-Objects of various 
  11.         seashells (Ammonites, Slug-houses etc.) 
  12.         for: POV-V2.0, Real3DV2 and T3Dlib (the last means Imagine, 
  13.         DXF, Rayshade, Vort, Post-Script etc. support! ). 
  14.         (take a look at "examples.jpg")
  15.  
  16.         It uses an algorithm found in:
  17.          Computer&Graphics Vol. 17,No. 1,pp. 79-84, 1993
  18.          ("DIGITAL SEASHELLS" by M.B. Cortie.)
  19.  
  20.         It was written in (portable) C using GCC2.3.3 with TDS, on
  21.         an AMIGA.
  22.  
  23.         The POV output of Shelly consists of triangles.
  24.         The Real3D output is a RPL-Macro executable via
  25.         "Execute named" in the "Macros"-menu and produces 
  26.         a big B-Spline-mesh.
  27.         The T3D-output can be converted via TDDD2xxx to many different
  28.         formats (of course you'll have to get the converters first)
  29.         (available on Aminet, look in 'gfx/3d' ...)
  30.  
  31.         Have fun !
  32.  
  33.  
  34.        Changes:
  35.        ¯¯¯¯¯¯¯¯
  36.        
  37.        from V1.3 to V1.4:
  38.        ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  39.        - fixed a bug in the NODULE calculation-mode (Shelly could end up
  40.          in an infinite loop for some parameters)
  41.  
  42.        - fixed a bug that caused "Float-Exceptions" (when calculating
  43.          shells without nodules) on Alpha-Architecture (and others?)
  44.        
  45.        - added "RENDER"-feature (Shelly calls POV itself to render a 
  46.          preview)
  47.        
  48.        - added "Scale"-feature (the shell may be scaled now)
  49.  
  50.        - Shelly now supports 3 different nodule-types in one shell
  51.          (see threenod.shy)
  52.        
  53.        - Shelly now produces outputfiles that tell the right version ;)
  54.        
  55.  
  56.        from V1.2 to V1.3:
  57.        ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  58.        - fixed a bug in the nodule creation (nodules were not 
  59.          symmetrical)
  60.        
  61.        - added new calculation mode (I call it "dynamic_stepsize"),
  62.          please consult the Usage section!
  63.        
  64.        - added new outputtype ("RAW")
  65.        
  66.        - shelly uses a temporary file for calculation of the camera-
  67.          position (rather than calculating all points twice) now!
  68.  
  69.               
  70.        from V1.0 to V1.2:
  71.        ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  72.        - added "autofocus" for POV-output (automatic placement of the 
  73.          camera in the right distance) 
  74.  
  75.        - the file 'shelly.pov' is never consultet now!
  76.        
  77.        - the RPL-output now generates much (100 times) smaller objects
  78.  
  79.        - added T3Dlib-support (new Keyword is 'T3D'!)
  80.        
  81.        - the silly countdown is gone
  82.        
  83.        - this time Shelly comes with only one guide ! (hope so :))
  84.  
  85.        
  86.         CONTENTS:
  87.         ¯¯¯¯¯¯¯¯¯
  88.  
  89.         shelly.lha contains:
  90.  
  91.          - shelly (the executable for C= Amiga (should work on all Amigas))
  92.  
  93.          - shelly20 (a special version of the exe that uses MC68020 and up 
  94.                      & MC68881 and up)
  95.  
  96.          - shelly.c, shelly.h (source & header, ready to compile on various
  97.                                machines)
  98.  
  99.          - examples.jpg (a picture of all examples) 
  100.                         (except 'Lyria' all Shells rendered on my Amiga 
  101.                          (A4000/030, 2C/2F) with Real3D2(Demo:)))
  102.  
  103.          - Planorbis.shy, Nautilus.shy, Lyria.shy, Ammonite.shy
  104.            Oxystele.shy, Natalina.shy           (some example data-files)
  105.  
  106.          - Shelly.guide (this document)
  107.  
  108.          - Blank.shy   (a blank datafile)
  109.  
  110.          - nodule.gif  (example-picture of the results of the new
  111.                         calculation-mode)
  112.                         
  113.  
  114.         REQUIREMENTS:
  115.         ¯¯¯¯¯¯¯¯¯¯¯¯¯
  116.  
  117.  
  118.         Shelly requires atleast:
  119.  
  120.          (to use the executables provided)
  121.  
  122.           - an Amiga (harddisk & fast processor recommended)
  123.           
  124.           - 'ixemul.library' (NOT in this package!!!)
  125.  
  126.           - POV-V2.0 or Real3DV2 to look at the results
  127.  
  128.           - or the TDDDlib-converters if you want Shelly to 
  129.             create objects for Imagine etc.
  130.          
  131.           Shelly has been tested on the following configurations:
  132.           -A4000/030
  133.           -A2000D+A2630
  134.          
  135.          
  136.          
  137.           Shelly compiled with no problems on 
  138.           IBM-RS6000,SUN4,HP9000/345,CONVEX
  139.          
  140.          
  141.  
  142.         INSTALLATION:
  143.         ¯¯¯¯¯¯¯¯¯¯¯¯¯
  144.  
  145.         The installation of Shelly is very easy ...
  146.         Just copy the Drawer "Shelly" to a place 
  147.         where you like to install it. 
  148.  
  149.         and give it a '(g)cc shelly.c -o shelly -lm' (not needed on Amiga)
  150.  
  151.  
  152.  
  153.         QuickStart:
  154.         ¯¯¯¯¯¯¯¯¯¯¯
  155.  
  156.         To get started quickly :
  157.  
  158.          - install Shelly (described in Installation)
  159.  
  160.          - open a shell (CLI), cd to the directory "Shelly"
  161.  
  162.          - type 'shelly Planorbis.shy xxx.pov'
  163.            (Planorbis is one of the examples, xxx is the name of the 
  164.             POV-Scene Shelly will create)
  165.  
  166.          - now go and render the file 'xxx.pov'
  167.            (e.g. 'pov -ixxx.pov -f +d' (assuming you have pov in your path))
  168.  
  169.          perhaps you have to edit the file 'xxx.pov' (camera position etc.)
  170.          and try it again to get the best result... 
  171.  
  172.        For detailed information look into the Usage section.
  173.  
  174.         GENERAL
  175.         ¯¯¯¯¯¯¯
  176.  
  177.         just type
  178.  
  179.         'Shelly infile outfile'
  180.  
  181.         to run Shelly from a shell (CLI)
  182.         
  183.         - infile is the (path+)name of a datafile
  184.         - outfile is the (path+)name of the POV/RPL/T3D/RAW outputfile
  185.  
  186.         - outfile will be overwritten (if it exists)!
  187.         
  188.         - Shelly will also open a file "(path+)outfilename.tmp"
  189.           and overwrite it (this is a temporary file, it will be
  190.           deleted after calculation)
  191.  
  192.  
  193.         DATAFILES:
  194.         ¯¯¯¯¯¯¯¯¯¯
  195.  
  196.         Shelly uses own datafiles in a simple format to get 
  197.         the arguments into the program.
  198.  
  199.  
  200.            Fileformat:
  201.            ¯¯¯¯¯¯¯¯¯¯¯
  202.  
  203.         The files are of a very simple (and easy to process :)) format:
  204.  
  205.         - every line of the file is scanned for keywords.
  206.  
  207.         The following keywords are supported:
  208.  
  209.  
  210.         'alpha:'
  211.         'beta:'
  212.         'phi:'
  213.         'omega:'
  214.         'my:'
  215.         'smin:'
  216.         'smax'
  217.         'sd:'
  218.         'omin:'
  219.         'omax:'
  220.         'od:'
  221.         'P:'
  222.         'L:'
  223.         'A:'
  224.         'a:'
  225.         'b:'
  226.         'W1:'
  227.         'W2:'
  228.         'N:'
  229.         'RPL' (switches to RPL-output)
  230.         'POV' (guess)
  231.         'T3D' (hmm)
  232.         'RAW' (simply the coordinates of the created triangles)
  233.                 
  234.         'NORMAL' (default calculation mode)
  235.  
  236.         'NODULE' (switches to new @{"calculation mode" link calcmod} (dynamic stepsize) 
  237.                   only useful when rendering shells with nodules!)
  238.                   
  239.         'o2d:' defines the stepsize used in nodules (only in NODULE-mode)
  240.         
  241.         'Threshold:' special value for detecting nodules (0.0005 - 0.5)
  242.                      as higher the threshold as smaller is the as 
  243.                      nodule-area detected area
  244.  
  245.     NEW in V1.4:
  246.         
  247.         'Scale:' defines a scale factor for the shell (default is 1.0)
  248.  
  249.         'RENDER' switches preview on (Shelly will automatically call POV
  250.                  after calculation)
  251.                  ONLY available when output-type == POV! and
  252.                  'pov' must be in the search-path!
  253.                  POV will just render the picture! no file is created
  254.                  (options for pov-call are "-f +d -iyour_pov_output") 
  255.  
  256.         'POVARGS:' defines arguments of the pov-call
  257.                    default is "-f +d +w200 +h160")
  258.                    use of this keyword overwrites all default-arguments 
  259.                    passed to pov! 
  260.                    (be sure to specify a complete argument-string for pov)
  261.                    -ixxx is added automatically (don't use this!)
  262.  
  263.         'P2:'    P of second nodule
  264.         'W12:'   W1 of second nodule
  265.         'W22:'   W2 of second nodule
  266.         'L2:'    L of second nodule
  267.         'N2:'    N of second nodule
  268.         'Off2:'  offset (in W2 (O) direction) between 
  269.                  nodule1 and nodule2 (in degrees)
  270.                  
  271.         'P3:'    P of third nodule
  272.         'W13:'   W1 of third nodule
  273.         'W23:'   W2 of third nodule
  274.         'L3:'    L of third nodule
  275.         'N3:'    N of third nodule
  276.         'Off3:'  offset (in W2 (O) direction) between 
  277.                  nodule1 and nodule3 (in degrees)
  278.  
  279.  
  280.         (note that the ':' belongs to the keyword!  you can use
  281.          for instance the word 'alpha' with no risk in comment lines)
  282.  
  283.         (The meaning of a special parameter (keyword) can be found
  284.          in the section about the algorithm.)
  285.  
  286.  
  287.         - if a line contains no keyword it is treated like a comment
  288.  
  289.         - if a line contains a keyword it is interpreted 
  290.           (the number behind the keyword is copied into an internal structure 
  291.            ("alpha:30" sets the internal alpha value to 30) 
  292.           or a flag is set
  293.            (the 'RPL' keyword sets the flag "we_have_to_produce_an_RPL-file"))
  294.  
  295.         - as you can see we have keywords that need parameters behind them
  296.           and keywords that just have to be there to set something
  297.  
  298.         - the only "Flag-keywords" the program knows are: 'POV','RPL','T3D',
  299.           'RAW','NORMAL','NODULE','RENDER'
  300.           all other keywords need to be combined with a number 
  301.           (as the ':' states)
  302.  
  303.         - everything is casesensitive! ('RPL' != 'rPl')
  304.  
  305.         - the file is not checked for anything else
  306.  
  307.         - double use of the same keyword causes an overwriting of the
  308.           last set value
  309.  
  310.         - lines like "alpha:Blafasel" will cause NO errormessage
  311.           (there are no messages at all ;))
  312.  
  313.  
  314.         note: the keyword does not have to stand alone!
  315.               if you write a line like:
  316.  
  317.               "/*RPL*/" or "BlafaseRPLl"
  318.  
  319.               the RPL-flag will be set! But you could also write:
  320.  
  321.               "render this in RPL pleazze :)"
  322.  
  323.  
  324.  
  325.         There is a special file ("Blank.shy") prepared for you that is blank
  326.         (contains only the keywords).
  327.  
  328.         consider:
  329.  
  330.          - some parameters have to be given in degrees, some not
  331.            (look into the algorithm section)
  332.  
  333.          - if you want Shelly to create a RPL file as output add a line
  334.            like "RPL" or "pleazze do it in RPL" to the file
  335.            ("T3D" will switch to T3D-output)
  336.            (POV output is default)
  337.  
  338.          - be careful with the parameters, don't try to fool Shelly 
  339.            ("what does it do if i enter an infinite value :)?") 
  340.            it will end up in a mess or coredump or our beloved friend! 
  341.            because the values are not checked!
  342.            
  343.            You should just change the given examples slightly until you 
  344.            know what you are doing...
  345.  
  346.          - smin,smax,sd,omin,omax,od are very critical parameters
  347.            because they determine the size of the output and the memory
  348.            consumption while calculating the shell   
  349.  
  350.          - o must be positive! (omin >= 0, omax > omin, od > 0)
  351.  
  352.          - always remember:
  353.            This program has still the status "experimental"!
  354.  
  355.          - there is a new calculation mode in V1.3 (Modi).
  356.  
  357.  
  358.        CALCULATION MODI:
  359.        ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  360.        
  361.        
  362.           The NODULE-MODE:
  363.           ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  364.  
  365.  
  366.        This is a new calculation mode that can save object-data, up to 40%!
  367.        (only in shells with nodules) 
  368.  
  369.        It is called "dynamic_stepsize" and can be invoked by using the
  370.        NODULE keyword. (default mode is NORMAL)
  371.        
  372.        How it works:
  373.        
  374.        - imagine a shell with nodules (look at "nodule.gif"),
  375.          if there is enough space between the nodules it might be
  376.          possible to increase the stepsize (in o-direction)
  377.          between the nodules without loss of information.
  378.  
  379.          (in fact the NODULE-mode uses the old stepsize (od) between the
  380.           nodules and the stepsize given via new keyword o2d in the nodules)
  381.           
  382.        - this means high resolution is only used when needed (in the nodules)
  383.          the rest of shell is calculated in a lower resolution
  384.          
  385.        - Attention! 
  386.          In this new mode it is possible to choose a stepsize (od) that
  387.          is bigger than the size of the nodules (W2) without fear of missing
  388.          nodules ("jumping" over a small nodule with a big step)
  389.          ALL nodules are calculated correctly.
  390.          
  391.        - o2d is the stepsize that is used in the nodule 
  392.          (This (o2d) should be smaller than the nodulesize (W2) ofcourse)
  393.        
  394.        - the value given via 'Threshold' is used to detect nodules,
  395.          this should be a small number (0.0005 - 0.5) 
  396.          (as higher the threshold as smaller is the as 'nodule-area' 
  397.          detected area)
  398.          (depends on the size and height of the nodules) 
  399.          you have to experiment with this if you want to reach the best
  400.          results (start with a small value and increase it)
  401.         
  402.        - a big influence on the result has the relation between 
  403.          od, o2d and W2 (I prefer 10 to 4 to 15) (experiment!)
  404.  
  405.  
  406.          PROBLEMS
  407.          ¯¯¯¯¯¯¯¯
  408.  
  409.            - it is nothing to be seen in POV:
  410.               probably the camera/light positions are wrong       
  411.               take a look at the data in your pov-file and correct this
  412.        
  413.  
  414.            - POV tells me something from "degenerated triangles"
  415.               well this problem did not occur yet (in shelly) but i know
  416.               it could happen (former projects)
  417.               nothing serious, just some triangles with 2 points the same        
  418.  
  419.                      
  420.            - Real3Ds annoying "Stack full" message comes up everytime
  421.              a macro is executed:
  422.              
  423.               - change the RPL-stacksize (menu: Settings/RPL)
  424.                  (increase the "Parameter Stack")
  425.               - open a new RPL-window
  426.               - type: '"(path+)macroname" LOAD'
  427.  
  428.  
  429.            - strange numbers (NaN's) occur in the output:
  430.  
  431.               Well this problem is known to me but no solution (sorry).
  432.               
  433.               Since the algorithm is somewhat complex i really don't 
  434.               want to have to find out which combination of which 
  435.               parameters cause this.
  436.               
  437.               It is also a problem of the sideeffects and (numerical)
  438.               stability of the "mathematic" functions i call.
  439.               
  440.               note: i suppose zeros are the source of all this
  441.                     -> try to avoid them          
  442.  
  443.  
  444.  
  445.         Hints
  446.         ¯¯¯¯¯
  447.  
  448.         for Real3D-users:
  449.         
  450.         - remember that in a B-Spline-mesh the first and last line 
  451.           (and in each line the first and last point) 
  452.           of the mesh will be invisible (unless you switch objecttype
  453.           to Polygon or Phong) 
  454.           this means for a shell with smin:10, smax:210, sd:20 that you
  455.           will see a shell created from smin:30 to smax:190!
  456.           (all examples will suffer from this if you just add the RPL
  457.            keyword)
  458.           solution: increase the ranges of s and o.
  459.  
  460.  
  461.         - if you want nodules in RPL-objects:
  462.  
  463.           You should choose proper values of od and sd to see the nodules
  464.           at all
  465.            (if you have nodules that are 10° wide (in o-direction) and you 
  466.             choose an od of 40° you will see probably no nodules!)
  467.            (this is also important for the POV-output)
  468.  
  469.           You should double the nodule height (L) for B-Spline objects 
  470.           to get the same height of the nodules as a POV-output!
  471.  
  472.  
  473.         - if you want to create a shell without nodules you may
  474.           double the sd and od values for B-Spline objects without loss
  475.           of quality in many cases
  476.  
  477.  
  478.  
  479.         The Algorithm:
  480.         ¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  481.  
  482.         In this section you will find more detailed information on the 
  483.         algorithm used by Shelly and on the parameters it uses.
  484.  
  485.         - The basic idea of the algorithm is to simulate a shell shape
  486.           by rotating & moving (©ing) an ellipse (or a part of an 
  487.           ellipse, or any other curve (a cardiod)) around an axis.
  488.           This will end up in some sort of spiral-shape.
  489.  
  490.         - The shape produced will depend on many things like:
  491.                -starting size/place/orientation of the ellipse
  492.                -exact form of the ellipse (nodules)
  493.                -how fast is the ellipse growing while rotating etc.
  494.  
  495.         - you can find the exact formulas in the original article or
  496.           in the sourcecode (too lazy to write them here again, they are
  497.           very complex)
  498.  
  499.         - here is a list of all parameters that shelly needs to generate 
  500.           a shell:
  501.  
  502.          -angular parameters (given in degrees):
  503.           alpha    :equiangular angle of spiral
  504.           beta     :angle between z-axis and line from aperture local 
  505.                     origin to xyz-origin
  506.           phi      :tilt of ellipse major axis from horizontal plane
  507.           omega    :amount of azimuthal rotation of aperture
  508.           my       :amount of "leaning over" of aperture
  509.  
  510.           smin     :angle at which aperture generating curve begins
  511.           smax     :angle at which aperture generating curve ends
  512.           sd       :stepsize in s-direction
  513.           omin     :angle at which spiral begins
  514.           omax     :angle at which spiral ends
  515.           od       :stepsize in o-direction
  516.  
  517.           P        :position of nodule, in terms of angle s
  518.           W1       :width of nodule in s-direction
  519.           W2       :width of nodule in o-direction
  520.  
  521.          -linear dimensions
  522.           A        :distance from main origin of aperture at o=0
  523.           a        :major radius (long axis) of ellipse at o=0
  524.           b        :minor radius (short axis) of ellipse at o=0
  525.           L        :height of nodule at o=0
  526.  
  527.          -other
  528.           N        :number of nodules per whorl
  529.  
  530.  
  531.         - the parameters smin,smax,sd,omin,omax,od determine
  532.           how many triangles (controlpoints) are generated
  533.           (how smooth is the shell and how many whorls are generated) 
  534.           -> be careful with these: memory usage and filesize depend 
  535.              directly on this parameters
  536.  
  537.         - the parameters alpha,beta,phi,omega,my determine the orientation
  538.           of the ellipse before (and while) rotating
  539.  
  540.         - the parameters A,a,b determine starting place and size of the 
  541.           ellipse
  542.           
  543.         - the parameters P,N,L,W1,W2 determine number,size and place
  544.           of nodules
  545.  
  546.  
  547.  
  548.         Credits:
  549.         ¯¯¯¯¯¯¯¯
  550.  
  551.  
  552.         - M.B. Cortie for his article "Digital Seashells"
  553.         - Martin Huttenloher for the icon of the guide
  554.           (Thanks for MagicWB!)
  555.  
  556.         Thanks to the people who ported GCC & CSH to the Amiga
  557.         and to Soulman (IRC) who helped me to realize the difference
  558.         between 2 and 2.0 ;).
  559.  
  560.  
  561.  
  562.         DISTRIBUTION:
  563.         ¯¯¯¯¯¯¯¯¯¯¯¯¯
  564.  
  565.         Shelly may be distributed FREELY via any media as long as:
  566.  
  567.         1) The archive shelly.lha and its content remains unchanged.
  568.  
  569.         2) No money (except a small copying fee) changes hand.
  570.  
  571.  
  572.  
  573.         (Although Shelly is Freeware i won't reject gifts like
  574.          money, chocolate, your latest piece of (gfx related) code etc..
  575.          My adress can be found below..)
  576.  
  577.  
  578.  
  579.         DISCLAIMER:
  580.         ¯¯¯¯¯¯¯¯¯¯¯
  581.  
  582.         This program comes with no warranty, either expressed or implied.
  583.         The author is in no way responsible for any damage or loss that 
  584.         may occur due to direct or indirect usage of this software.
  585.         Use this software entirely at your own risk.
  586.  
  587.  
  588.         ADDRESS:
  589.         ¯¯¯¯¯¯¯¯
  590.         send 
  591.         chocolate, money, your programs, bug reports (NOOOOOOO!:) etc.
  592.         to:
  593.  
  594.         Randolf Schultz
  595.         Unter den Linden 51
  596.         19079 Mirow
  597.         GERMANY
  598.  
  599.  
  600.         INTERNET: rschultz@informatik.uni-rostock.de 
  601.  
  602.                   or (not regularly read)
  603.                   
  604.                   tfb512@hp1.rz.uni-rostock.de
  605.          
  606.  
  607.         
  608.